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I n t r o d u c t i o n 



SECTION 1 
I n t r o d u c t i o n 



1 . 1 Ge ne ra 1 I n f o rma t i o n 

Be sure to write protect the installation tape. Before you 
attempt to install this toolkit? consult the System Re=juirements 
paragraph belotu. You will also need to applv all patches to the 
Explorer svstem software. 



i . 2 P r o d u c t Media 

If YOU purchased the object kit? the cartridge tape you received 
should be labeled: Explorer NLMenu CtbJect Distribution Tape. 
(Refer to the cover page for the correct TI part number.) This 
tape contains object files for the toolkit? as well as source and 
object files for the starter kit. 

If YOU purchased the source kit? the cartridge tape you received 
should be labeled: Explorer NLMenu Source/ObJect Distribution 
Tape. (Refer to the cover page for the correct TI part number. ) 
This tape contains all of the object kit components? plus the 
source files for the toolkit. 



i . 3 S Y stem Re *=! u i r e me n t s 

This installation procedure re^juires an Explorer SYstem with the 
f ol 1 owing: 

* A tape drive. 

* Space on the SYS-host file band to accommodate this 
toolkit's files. See the Release Information section 
for expected sizes for this release. 

* Space on the local disk for another load band? if you 
want to save the image after Your installation. See the 
Release Information section for expected sizes for this 
rel ease. 

* Explorer Release 2.0 SYstem or a later revision. 
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The NlMenu toolkit uses procedures in the Graphics 
toolkit. Graphics installation must precede that of 
NLtienu. The NLMenu toolkit also can make use o-F 
procedures in the RTMS toolkit. If you purchased the 
RTMS toolkit? it must be installed before the NLMenu 
toolkit. 
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SECTION 2 
Distribution Tape Installation 



2. 1 Introduction 

This section describes hoiu to install an Explorer sottujare 

product from an Explorer Distribution Tape. This installation 

procedure applies to all toolkits and to anv other add-on 
software available on Distribution Tapes. 

* You muRt read the INSTALLATION RESTRICTIONS paragraph to 
tell which file server hosts you can use. 

■«• You should read the INSTALLATION CHECKLIST paragraph to 
tell what information you need before you start. (This 
will save you time hunting up details during the 
instal 1 at ion. ) 

•«• You maY read the INSTALLATION OVERVIEW paragraph if you 
want a feeling for what is going to happen. (You will 
be prompted at each step and Your options fullY 
explained? so this overview is optional.) 



2.2 Installation Restrictions 

This paragraph itemizes the restrictions and limitations that 
currentlY apprv to this installation procedure. 



2.2. 1 UNIX Hosts. 

You cannot use anr host running under anY version of UNIX as a 
file server? as a SYS-host? or for the temporary working 
directorr. 



VAX VMS Hosts. 



You cannot use a VAX host running under anr version of VMS 
earlier than 4.0 as a file server or a SYS-host because it does 
not allow long file namestrings. It can be used for the working 
directorY (which del i berate 1y uses short namestrings). 
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You cannot use a VAX host running under VMS Version 4.0 or higher- 
using TCP/IP network protocol unless that TCP/IP implementation 
supports VMS 4*s Ions namestrinss. Some Version 4 
implementations still restrict you to Version 3" s shorter 
namestrinss. Symptoms of this problem include! 

* The Load Distribution Tape step appears to work fine? up 
to a point. 

■a- You set an error message to the effect that some 
particular file is "off limits" to you. 

* Logging on to the VAX over TELNET or the VTIOO Emulator 
will probablY show that the destination directory on the 
VAX looks correct. 

* Doing a Dired of that directory from your Explorer will 
probably show at least some truncated file names marked 
as being inaccessible. 



2,2.3 Directory Creation, 

Some operating systems? as a matter of policy? do not allow 
remote software to create directories over the network. 
Unfortunately? the installation software cannot distinguish a 
simple refusal from an actual network or file system failure. 
Therefore? the installation software will show you the text of 
the error message it received. If you are able to use TELNET or 
the VTIOO Emulator to log on to that host and correct the problem 
(e,g.? create the directory manually)? then you can return to the 
Backup window and resume loading the Distribution Tape. 



2.2.4 VAX Chaos Hosts. 

Some VAX implementations of the Chaosnet protocol will pad out 
non-character files to an integral number of blocks causing the 
Explorer tape verify to fail. If this should happen? then xnn 
must decide what to do. The installation software will warn you 
about what it thinks has happened and offer you the opportunity 
to =iuit or to accept the padded file and continue. It is known 
safe for Explorer XFASLs? but what happens with other types of 
files is not predictable. 



2.2.5 TCP/IP Hosts. 

In general? the TCP/IP network protocol offers less sophisticated 
network capabilities and error handling than the Chaosnet 
protocol. Therefore? the installation software is able to do 
less for YOU on a TCP/IP host? (e.g.? cannot tell why a remote 
server did not respond? etc.). 
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2.3 Installation Checklist 

The following is a list of ujhat you will need and what 
inf oriTiation you should gather before you start an installation. 



2.3.1 Tape Cartridses. 

You will need a Distribution Tape cartridge for each product you 
wish to instal 1 . 

Some Explorer software products are sold in two versions! object 
and source. These names cause some unfortunate confusion. A 
Distribution Tape with "object" on it contains all of the 
product's XFASL files that need to be loaded into memorr plus anY 
auxiliary source files that might also be needed (e.g.? the 
product's DEFSYSTEM file). A Distribution Tape with "source" — 
despite its name — contains both LISP source and XFASL object 
files. That is» 

•ff- an object tape contains everything to load and execute 
the product; 

■ff- a source tape contains everything to £.amBi.l.&.^ Ijciad? and 
£txitcut& the product. 

Regardless of whether you have an "object" tape or a "source" 
tape? the installation steps are the same — the source 
installation Just takes longer. A source tape tYPicallY Just has 
more files in its directory than the object tape has. In 
particular? you do not have to perform additional steps to get 
the "other" set of files loaded. 



2.3.2 SYS-Host. 

Unless the product-specific Release Information in Section 3 of 
this document sars otherwise? the SYS-host is re'^iuired to hold 
onlY the product's SYSTEM file and the TRANSLATIONS file for anY 
logical hosts it uses. The product's actual source and object 
files will be installed on the file server specified in its 
TRANSLATIONS file. Later in the installation? you will be given 
the opportunitY of editing all TRANSLATIONS files. 

Therefore? the product's files are not re^iuired to be installed 
in the SYS-host although theY maY be if you wish. The 
installation software does not actually care which SYS-host you 
use as long as you use the same one for both the Load 
Distribution Tape step and the INSTALL-NEW-PROGRAM step. 

You should make sure that Your SYS-host is set to the proper 
machine. You can find out what the current SYS-host is bY 
entering the form 
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( TRANSL ATED-PATHNAME " SYS : " ) 

to a Lisp Listener. You can chanse the SYS-host bv enter-ins the 
form 

(SI: SET-SYS-HOST < h o s t n ame > ) 

where <hostnarrie> is the network name o-F the machine you want to 

use as a SYS-host written as a strins (e.g.? "EXPl") or a symbol 

(e.3.7 -EXPl). C Not ice that there is no trailing colon in this 
host name. D 

When YOU complete the Load Distribution Tape step? it will remind 
YOU of Your temporary working directory and your SYS-host. When 
YOU start INSTALL-NEW-PROGRAM? it will ask you for both pieces of 
information. It has to ask because the reboot after the Load 
Distribution Tape step wipes out its memory. 



o 



Explorer System Source Files. 



Since most people will not be using the Load Distribution Tape 
software most of the time? most of this software is kept on disk 
in the file band (rather than the load band). The first time you 
click on the LOAD DISTRIBUTION TAPE item in the Backup window 
after a cold boot? you will see a message telling you there will 
be a short pause while it loads the remainder of the software. 
After the first time? later executions of Load Distribution Tape 
start right away. 

The Load Distribution Tape step is fully automatic and you should 
never need be concerned about it. However? when it starts? it 
looks for its external files on the " SYS s STREAMER-TAPE? " 
directory. That is to say? it looks for the STREAMER-TAPE 
directory on whatever machine is identified as SYS-host at the 
time. SYS-host is normally set to the machine that holds the 
Explorer system source? and the STREAMER-TAPE directory is part 
of the system source. There is usually no problem unless SYS- 
host is set to some other machine when you first click on LOAD 
DISTRIBUTION TAPE. 

If the current SYS-host does not contain the re=iuired files? the 
software will explain the problem and suggest that you change 
SYS-host to be a machine with the Explorer system source and try 
again. You may use different SYS-hosts for your Explorer system 
source and the new software you are installing. 

Therefore? when you click on the Load Distribution Tape item for 
the first time and Load Distribution Tape cannot find its 
external files? then: 
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1. Abort out of Load Distribution Tape. 

2. Go to a Lisp Listener and use SI : SET-SYS-HOST as 
described above to set SYS-host to a machine that has 
the Explorer sYstem source. 

3. Return to the Backup window and once asain click on the 
LOAD DISTRIBUTION TAPE item of the Backup menu (it 
should load this time). 

4. Once the files are loaded? go to a Lisp Listener and 
set SYS-host to where you want Your SYSTEM and 
TRANSLATIONS files to be (as explained above) then 
return to the Backup window and continue. 



2 .3,4 Wo r k ins Direct o r y . 

In addition to the directories needed bY the products you are 
installing* the installation software needs a temporary working 
directors. The Load Distribution Tape step leaves one file in 
this directors for each product it successfully copies to the 
file band. After the reboot? the Install New Program step uses 
this directorr to decide what is available for installation. 

The installation software will create the directorr for you. It 
will provide a default directorr name or allow you to specifr a 
different one. If the machine on which rou are doing this 
installation has a local file srstem? then it is simplest to 
accept the default. 

You need to keep this working directorr around until you have 
finished the Install New Program step. After that? you mar 
delete this directorr. In particular? as long as this directorr 
exists? YOU can execute the INSTALL-NEW-PROGRAM function as manY 
times as rou wish. Once rou have deleted it? rou will have to 
load the Distribution Tapes again. 

All of the Distribution Tapes rou load during the Load 
Distribution Tape step will use the same working directorr rou 
specified at the start. However? if rou execute Load 
Distribution Tape more than once? it will not currentlr let rou 
add new products to those alreadr on a previous working 
directorr. Instead? rou must create another working directorr. 

Using multiple working directories causes no particular problem. 
When rou finish the Install New Program step for one directorr? 
but before rou do the garbage collect step? exit the first 
INSTALL-NEW-PROGRAIi and execute a second Install New Program? 
this time specifring a different working directorr. When rou 
finish the Install New Program step for the last working 
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directory! do the sarbase collect step. 

2r,3., 5 Translations Files. 

Each product has one or more TRANSLATIONS files. These 
TRANSLATIONS files determine where the product's files will be 
stored on disk. Therefore^ you should know which file server (s) 
YOU want to use before you start the installation. 

You will be presented with a default TRANSLATIONS File for each 
logical host the product re«?uires (usually there is only one). 
That default file assumes that 

* YOU want to use the current SY£i— host as the file server 
for this product's files? and 

* the current SYS-host accepts Explorer pathname syntax. 

However? the product's files do not have to be installed on the 
SYS-host. If YOU want them somewhere else? then chanse the 
TRANSLATIONS file. You will be siven an opportunity 

* to accept the TRANSLATIONS File as is? 

* to edit it manually? or 

* to have the installation software edit it for you. 

The circumstances under which it can modify the file for you are 
explained in the prompts at the time. 



2.4 Installation Overview 

The following paragraphs describe the maJor steps in the 
installation procedure (which includes both the Load Distribution 
Tape and Install New Program steps) so that you will have some 
idea of what to expect. Details are deliberately not included 
here. Instead? you will be prompted at each stage for what is 
needed. Furthermore? each of your inputs is immediately 
validated to avoid later obscure errors. 



2.4.1 General Prompting Se«iuence. 

The Load Distribution Tape step (which accomplishes the tape-to- 
file-band transfer described next) has a number of prompts. Each 
prompt usually gives you the option of pressing RESUME to 
continue or ABORT to =iuit. 
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The first few prompts about the SYS-host and working directories 
are done onlv once regardless of how irianv Esistribution Tapes you 
install. The remainder of the prompts are in a larse loop that 
starts bv telling you to insert a Distribution Tape cartridge. 
When the tape-to-file-band transfer for the current Distribution 
Tape is complete^ there will be a message saring whether it 
completed normally or abnormal 1y. 

In either case? once you acknowledge the completion message? the 
Program returns to the earlier prompt asking you to insert a 
Distribution Tape cartridge (the SYS-host and working directory 
prompts are not repeated). At this point? you mar put in a new 
Distribution Tape and do it again or simplY end. 



2.4.2 Tape to File Band. 

The program automatical 1 y prepares the tape? selecting the 1/4" 
s t ream i ng tape ? f o r yo u . Yo u can exe rcise this step but it is 
not necessarY. Now click on the LOAD DISTRIBUTION TAPE item in 
the menu from the SYSTEM B Backup window. This function copies 
the contents of the Distribution Tape to a disk (or disks) you 
s pec ifY. 

Permanent files will be added to the SYS-host and the file server 
host for Your machine (these maY be the same or different 
machines). A temporarY working directory will also be created on 
a ma c h i n e o f y o u r c h o ice. 

When this Load Distribution Tape band step is complete? 
everything you need to complete this installation is now on Your 
disk(s)? but the product has not been loaded into memory and 
therefore cannot be executed Yet. If you have several products 
to install? to save time you mar load all of their Distribution 
Tapes before going to the COLD BOOT step. 

2.4.2.1 Version Numbers. 

The files on the Distribution Tape carrr the version numbers that 
correspond to TI's master Explorer software database. It is 
convenient for you to maintain these same version numbers when 
YOU COPY a Distribution Tape to Your disk since ther provide a 
common ground for discussing problems with the Explorer Technical 
Support Line. 

The first time you install a product? the use of these original 
version numbers presents no problem. However? the correct 
installation of a newer release of a product you have previous 1y 
installed assumes two things: 

* a file on the Distribution Tape which has been updated 
will have version numbers higher than anr version of 
that file now on Your disk? and 
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* a file which has nat been updated in this release mill 
have a version number matching the highest version of 
that file now on Your disk (and these two files will be 
ident i cal ) . 

If the version number already exists on vour disk? a comment will 
be printed to the effect that a "different" file already exists 
by that name and that particular tape file will nat be copied to 
your disk. This message only means that the same version number 
exists" the system did not actually compare the two files to see 
if they were different. 

The second assumption that identical version numbers mean 
identical files will be violated if you have modified the 
Explorer directories by adding new versions of some files. The 
Load Distribution Tape step is supposed to be restoring files 
which are as new or newer than anything already on your directory 
(regardless of which version number it used). Therefore? the 
verify step always verifies the tape against the newest version 
of each file on your disk. This means! 

* If you have nat modified your Explorer directories? then 
everything will verify fine. The warning you may have 
gotten about a "different" file on disk really 
represented an identical copy of the file- 

* If? however? you did modify the directory? one or more 
files will fail to verify. 

So? if you restore using original version numbers and there is a 
verify failure? then either 

* there was a tape error during restore Cwhich is 
unl ikely] ? or 

* your directory has extra versions of some files on it. 

If you have version number problems? you may choose to have the 
files all restored as the "newest" version (i.e.? the file is 
copied to a version one higher than the highest version already 
on your disk). You are given this choice at the beginning of the 
restore step. 

Choosing to restore to the newest version to avoid version number 
collisions can cause other subtle problems. Many system 
utilities assume that the file FOO. XFASL#4 is the compiled output 
of the file F00.LISP#4 in the same directory. If someone has 
added a LISP file? say F00.LISP#5? to the directory without 
compiling it into a matching FOO. XFASL#5? then a restore of 
FOO. LISP from a Distribution Tape will become F00.LISP#6? while 
the restore of the matching XFASL file will become F00.XFASL#5. 
Therefore? if you are forced to restore to newest? to avoid 
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version number collisions? then you mar be introducins several 
annoyances which you will not see until later, 

2-4.2-2 Other Information. 

If YOU want to refresh rour memory about the Load Distribution 

Tape step while you are at the machine? enter 

< DOCUMENT AT ION ' MT : : LOAD~D I STR I BUT I ON-T APE -■ FUNCT ION) 

to a Lisp Listener* This docuffientation string irientions several 
slobal variables which allow you to control some processing 
options such as whether you want a "verbose" display of each 
action as it happens (default is silent). Also? the first pr omp„t 
YOU receive after starting a Load E»istr ibution Tape includes an 
extensive HELP prompt for the first time user. 

Remember that most of the installation software is not in Your 
permanent load band. Instead? the first time you click on th# 
LOAD DISTRIBUTION TAPE item in the Backup window after a cold 
boot? there is a pause while the rest of the Load Distribution 
Tape software is loaded in- 



2.4.3 Cold Boot. 

The initial Load E'istr ibut ion Tape step caused extra installation 
software to be loaded into memorY which will not be needed after 
Load Distribution Tape is complete. Therefore? after you have 
loaded the Distribution Tapes for all the products you want to 
install at this time? you should cold boot the system to set rid 
of that part of the installation software that is no longer 
needed . 

You are not re^fuired to reboot — the installation will still work- 
However? the extra installation software will become a permanent 
part of the new load band you will save in the final step. 



2-4.4 File Band to Memory. 

ImmediatelY after cold boot (you do not even have to 1 os on)? you 
enter the INSTALL-NEW-PROGRAM function to a Lisp Listener. It 
will prompt you for various information and will display a list 
of products in the temporary workins directory available for 
installation. If you want to refresh your memory about this step 
while YOU are at the machine? enter 

(DOCUMENTATION -INSTALL-NEW-PROGRAM -FUNCTION) 

to a Lisp Listener. 

When this step is finished? the products will now be loaded into 
virtual memory and ready to execute. You now have two choices: 
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* You mav skip the remain ins steps and either 

- execute the products nouj as a test of the 
instal 1 ation? or 

-- do another INSTALL-NEW-PROGRAM if you have 

products on other working directories to instal 1 

(then do one sarbasie collect and DISK-SAVE tor all 
of them). 

•«• You mav continue with the remaining steps to make sure 
what YOU have installed is now in virtual memorr 
permanent 1y. 

If YOU choose to skip the remaining steps? the new products you 
Just instal 1 ed wi 1 1 be available to you onlr until you cold boot. 
If YOU cold boot 7 then you will have to execute 
INSTALL-NEW-PROGRAM again. 

Since the products' files are permanent 1y on the file band? you 
will not have to load the Distribution Tapes again if you 
reboot — unless you have deleted the temporary working directors. 
If YOU have deleted the working directors* you will have to start 
all over and reload all the Distribution Tapes (see the paragraph 
on Version Numbers above). 



2.4.5 Garbage Collect. 

This step is an option offered to you bv INSTALL-NEW-PROGRAM Just 
before it completes. The process of loading the products into 
memorY creates garbage which you will normal 1y want to get rid of 
before saving the new load band in the next step- Again? this 
step is optional? but recommended. It should take 20-30 minutes? 
depending upon the size of Your page band and how much garbage 
YOU have. 



2.4.6 Disk-Save. 

At this point? Your virtual memorr should contain everYthing you 
started with in the original load band you booted under? plus 
each product you had INSTALL-NEW-PROGRAM load for you — but no 
garbage. This virtual memorr image? however? will go awaY on the 
next cold boot unless you use the DISK-SAVE function to copy that 
memorY image to a new load band on disk. DISK-SAVE is described 
in EnjQsiiiaiLiztlns Canneets and lanls. 

Up. until this point? the installation software has tried to do 
most of the work for you? but you must do the DISK-SAVE Yourself. 
Furthermore? an improperlr done DISK-SAVE can destroY the disk to 
the point that you can never boot it again. Therefore? 
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WARNINI3 

You MUST know what you are doing before you 
tr-Y to do a DISK-SAVE. 



2.5 Cross-Machine arid- Mul tiH^achine Installation - = 

You must use an Explorer with a tape drive to "do^'th^ Load 
Distribution Tape step, but the Explorer with the tape does not 
have to be the one on which you are installing th'^ "pr'oduci:; 
After the Load Distribution Tape step is complete,' YotimaY told 
b o o t an y Ex p 1 o r e r o n the same n e t w o r k an d ^o the 
INSTALL-NEW-PROGRAM step from it. -s ~..j; r " 

All the information needed f ot- the instal lation is carried in th^ 
SYS: SITE; director-Y and in the temporar-Y working directorY. When 
the INSTALL-NEW-PR0i3RAM starts, it asks for the name of the SVS- 
host and for the pathname of the working directorY? the Load 
Distribution Tape step and the INSTALL-NEW-PROGRAM step are 
independent. 

If Your software license allows it, a single Load Distribution 
Tape step on one Explorer on the network will suffice tor all 
I NSTALL-NEW-PROGR AM installations on other ma c h i n e s . 



^.o uistriDUTion rape f-ormat - 

A n Ex p 1 o r e r Ei i s t r i b u t i o n Tape is written out using the b r d i na r% 
Backup File and Backup Directory commands from the SYSTEM B 
Backup menu. Therefore, you can use the standard tape utilities 
to examine or even to manually restore the Distribution Tape 
Yoursel f . - . 

The first file on the tape is called the Restore File. The 
remaining files and directories are typical 1y the ordinary files 
needed br the product. The Restore File defines a function 
called LOAD-DISTRIBUTION-TAPE-I whose purpose is to read the 
remainder of the tape using various utilities. ' 

If YOU re^iuire a custom installation of a particular Distribut i«:>n 
Tape, YOU can use the standard tape utilities to copy the first 
file from the Distribiution Tape (the Restore File) to disk and 
look at it. From that Res t«:ire File, you should be able to decide 
what the remaining fi-le& on the tape are for and how to restore 
them. - . . 
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SECTION 3 
Release Information 



This section contains product—specific release information for 
the NLMenu toolkit. 



1 Special Notes 



•J*- Before you besin installing the NLMenu toolkit? you must 
first delete the following directories. 

- NLMENU: NLMENU; 

•K- If RTMS is to be installed on Your machine? you must 
also delete 

- NLMENU s NLMENU-RTMS- 1 NTERF ACE ? 

■«■ AIsoj before installing this toolkit* Your SYstem must 
have Streamer Tape patch 2.3 installed. If this patch 
is not in the load band* it is in the patch director/. 



The fol lowing are the expected sizes for this release: 

* 680 pages are needed to accommodate the object version 

* 1550 pases are needed to accommodate the source and 
object version 

•fi- If the image is saved after the installation* 1300 
blocks are added to Your load band 
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